// --------------------------------------------------------------------------------------------------------------------
// <copyright company="Collaboris Ltd." file="IMacro.cs">
//   Copyright (c) Collaboris Ltd. All rights Reserved.
// </copyright>
// <summary>
//   IMacro is an ordered list of IAction's. It receives particular IContext
//   that should be processed. IContext is processed by passing it to
//   actions available in IMacro(starting from first IAction in IMacro
//   to the last one).
//   IContext processing is performed until one of the IMacro's actions
//   returns true, one of the IMacro's actions throws an exception
//   or end of the IMacro's actions list is reached.
// </summary>
// --------------------------------------------------------------------------------------------------------------------

namespace Collaboris.Saf.Engine
{
    using System;
    using System.Collections.Generic;

    using Collaboris.Saf.Engine.Report;

    /// <summary>
    /// IMacro is an ordered list of IAction's. It receives particular IContext
    /// that should be processed. IContext is processed by passing it to 
    /// actions available in IMacro(starting from first IAction in IMacro 
    /// to the last one).
    /// IContext processing is performed until one of the IMacro's actions 
    /// returns true, one of the IMacro's actions throws an exception 
    /// or end of the IMacro's actions list is reached.
    /// </summary>
    public interface IMacro
    {
        #region Properties

        
        /// <summary>
        /// If an IAction in the macro fails (and StopOnDoException is true),
        /// then if AutoUndo is true, the "UnDo" method on each IAction 
        /// will be called in reverse order. (This includes the failing Action).
        /// </summary>
        /// <remarks>
        /// Note! In this situation if a seperate Undo Macro 
        /// has been designated it will not be used in this scenario.
        /// This mode effectively causes the "Do" Macrog to be executed in reverse
        /// order.
        /// </remarks>
        /// <value>The group.</value>
        bool AutoUndo
        {
            get;
            set;
        }

        /// <summary>
        /// Gets the ID for the Macro 
        /// Template
        /// </summary>
        /// <value>The ID.</value>
        Guid TemplateID
        {
            get;
        }

        /// <summary>
        /// Gets the ID for the instance 
        /// of the Macro Template.
        /// </summary>
        /// <value>The ID.</value>
        Guid InstanceID
        {
            get;
        }

        /// <summary>
        /// Gets the context.
        /// </summary>
        /// <value>The context.</value>
        SafContext Context
        {
            get;
        }

        #endregion

        #region Indexers

        IDictionary<int, IAction> Actions
        {
            get;
        }      
        
        /// <summary>
        /// Gets the <see cref="Collaboris.Saf.Engine.IAction"/> at the specified index.
        /// </summary>
        /// <value></value>
        IAction this[int index]
        {
            get;
        }

        #endregion

        #region Public Methods

        /// <summary>
        /// Reponsible calling 'Do' on all the IAction's
        /// in the macro. The IContext will passed from one 
        /// Action to the other allowing a predecessor to pass
        /// data and communicate with the next Actions in the 
        /// queue.
        /// </summary>
        /// <param name="context">
        /// </param>
        /// <returns>
        /// </returns>
        MacroReport Do(SafContext context);

        /// <summary>
        /// Reponsible calling 'Undo' on all the IAction's
        /// in the macro. The IContext will passed from one 
        /// Action to the other allowing a predecessor to pass
        /// data and communicate with the next Actions in the 
        /// queue.
        /// </summary>
        /// <param name="context">
        /// </param>
        /// <returns>
        /// </returns>
        MacroReport Undo(SafContext context);

        /// <summary>
        /// Gets a dynamic Variable matching the key.
        /// </summary>
        /// <param name="variableName">Name of the variable.</param>
        /// <returns></returns>
        object GetDynamicVariable(string variableName);

        #endregion
    }
}